Shareware Grab Bag

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Grab Bag / Shareware Grab Bag.iso / 050 / pasclib.arc / PASCLIB.DOC next >

Wrap

Text File | 1985-06-28 | 13.7 KB | 370 lines

PASCLIB Version 1.0 (Copyright 1985) ======================================================================= by: Gerry L. Kilgore 1725 Kellogg Springs Dr. Dunwoody, GA 30338 (404) 396-6107 (Voice) ======================================================================= PASCLIB is a library of floating point subroutines, a sine/cosine sub- routine, a random number function and a ramdomize program to seed the random number generator. The library was written in Assembler language primarily to interface with IBM/MS Pascal programs to obtain great speed without giving up single precision accuracy such as required by graphics programs using mathematical functions or plotting. Other applications, not requiring the accuracy of long precision can, of course, benefit from use of this library. WHY BOTHER?? Simply put, because they perform approximately five (5) times faster that the equivalent operations using short precision in IBM/MS Pascal. They are not hampered by generalized overhead. The library is equally useable by Assembler Language programmers. In fact, it was constructed with a separate EXTERNAL interface which, in turn, calls the INTERNAL routines. The Assembler Language programmer can bypass the EXTERNAL interface and go directly to the INTERNAL routines, if he obtains the A/L source. If not, he may still use the EXTERNAL calls. I am declaring this program in the Public Domain under the Freeware Concept. That is, you are free to copy and distribute this library as long as you do so without financial gain. If you find it useful, and feel that it is justified, this author will not turn down any contributions ($20.00 is reasonable). For your contribution of at least $20.00 along with a self-addressed diskette mailer with return postage affixed, I will send you a diskette with the commented Assembler Language source of PASCLIB, additional documentation on how to call the internal routines, and I will put you on my mailing list for notification of fixes, enhancements and upgrades. Send contributions to the address shown above. DISCLAIMER: This author will not be held accountable for any problems or damages associated with the use of PASCLIB whether they be physical, financial or psychological. If you use PASCLIB, you use it at your own risk! ====================================================================== WHAT'S IN THE PACKAGE? ====================== You have: PASCLIB.INC - the "INCLUDE" file for IBM/MS Pascal PASCLIB.OBJ - the subroutine object module. PASCLIB.DOC - this documentation. In IBM/MS Pascal, you must place an "INCLUDE" statement in your program as if you were defining a function or procedure. This will permit you to invoke the Functions and Procedures of PASCLIB.OBJ. That statement will be as follows: {$INCLUDE:'PASCLIB.INC'} with no semi-colon following the statement. You may, of course, pre- cede the name, PASCLIB.INC, with a drive specifier, such as, {$INCLUDE:'B:PASCLIB.INC'} if PASCLIB.INC is not on the default drive. PASCLIB.INC contains the following external procedure and function definitions: procedure randomize; external; function random ( n : integer): integer; external; function f_add( op1, op2: real): real; external; function f_sub( op1, op2: real): real; external; function f_mult(op1, op2: real): real; external; function f_div( op1, op2: real): real; external; procedure sinlook( arg: integer; var sin: real); external; procedure coslook( art: integer; var cos: real); external; function ifloat( arg: integer): real; external; function fltrunc( arg: real): integer; external; function fround( arg: real): integer; external; function fltmod (art: real): real; external; function rsin( arg: real): real; external; function rcos( arg: real): real; external; function craddeg( rad: real): real; external; In addition, you will need to insert the follwoing statement in your program in order to tell IBM/MS Pascal that you are working with SHORT Precision real numbers: procedure mpsrqq; external; This procedure is internal to the PASCAL.LIB library and is linked into your program automatically when you perform the LINK function. HOW DO I USE THEM? 1. Randomize is a procedure with no arguments. It seeds the random number generator for the function, Random. This is accomplished by accessing the system clock or timer. Use: randomize; That's all there is to that one. 2. Random is a function that returns a random integer. Use: y := random(a); or if ( random(a) > 50 ) then ........ 'a' must be an integer and random (a) will return a random integer such that 0 < random(a) < a. 3. F_add is a function that performs a single precision floating point add of two real numbers returning their real sum. Use: y := f_add (a, b); Adds 'b' to 'a' and returns their sum in y. 4. F_sub is the same as f_add, except for, y := f_sub (a, b); 'b' is subtracted FROM 'a' and the difference is stored in 'y'. 5. F_mult is a function that performs a single precision floating point multiplication of two real numbers returning their real prod- duct. Use: y := f_mult(a, b); 'a' is multiplied by 'b' and the product is stored in 'y'. I might add that these functions can be nested. For example: z := f_add ( f_mult ( a, b ), c ); is completely valid, since f_mult ( a, b ) is a real number and we presume that so is 'c'. 6. F_div is the floating point division function where if, y := f_div (a, b); then 'a' is divided BY 'b' and the quotient is stored in 'y'. In this case, 'a' is the dividend and 'b' is the divisor. Division by zero returns a zero, by the way. 7. Sinlook is a procedure that returns a real number which is the trignometric sine of an integer number of degrees. PASLIB.OBJ contains a sine/cosine table of the real sine of integer degrees. It can very quickly determine the sine of a number by performing a binary search on this table. Use: sinlook (a , b); where 'a' is the integer representation of the number of degrees and the sine of 'a' is returned in the real variable, 'b'. (Note that while 'a' may be a literal, 'b' MUST be a variable) For example: sinlook (30, b); returns the sine of 30 degrees as a real variable in 'b'. 8. Coslook is the same as sinlook except that it returns the cosine in the second variable. Thus, coslook (45, x); places the cosine of 45 degrees in the real variable, 'x'. 9. Ifloat is a function which creates a real number out of an integer. Though you can accomplish this with a simple assignment statement in Pascal, Ifloat performs it much, much faster. Use: y := ifloat (30); creates the internal floating point representation of '30' and puts it in the real variable, 'y'. It is included primarily for speed. 10. Fltrunc takes a real number and essentially throws away the fractio- nal portion of the number, yielding an integer. It is a function. Use: j := fltrunc (z); takes the floating point number in 'z' and truncates the fractional portion and stores the resulting integer in 'j'. 11. The Fround function is similar to fltrunc, except the resulting in- teger is 'rounded'. In decimal terms this is equivalent to rounding 32.7 up to 33, whereas, 32.1 would be 32. Use: i := fround(y); The real number in 'y' would be rounded to an integer and placed in 'y'. 12. The function, fltmod, returns the fractonal portion of a real number, throwing away the integral portion. In decimal terms, this is like creating 0.333 from 8.333. It's sort of the inverse of fltrunc. Use: r := fltmod ( s ); and the fractional portion of the real variable, 's', will be re- turned in the real variable, 'r'. 13. Rsin is what we are used to seeing in a sine function. It returns the sine of a real number representing radians, of course, as a real number. Use: y := rsin ( z ); where the real variable, 'z', contains the angle in radians, and we get the sine of that angle in the real variable, 'y'. The process used is that of table lookup (binary search) and interpolation be- tween the two angles in degrees that 'z' is between. 14. Rcos is the same as rsin, except the cosine of the angle is returned. Thus, x := rcos ( y ); 15. Craddeg is a function that simply converts radians to degrees, so, z := craddeg (r); converts the real number in 'r' from radians to degrees and stores the result in the real variable, 'z'. That's how to use it in IBM/MS Pascal in so far as the programming is concerned. The remaining step is to get PASCLIB physically accessible to your program. This is accomplished by LINKing PASCLIB.OBJ to your program. The simplest way to do this is shown by example. If your program, containing PASCLIB.INC and PASCLIB function/procedure usage, is called "MYPROG.PAS", then after a successfuly compilation through PAS1 and PAS2, to obtain MYPROG.OBJ, you would enter the following command at the DOS prompt: link myprog+pasclib; The result will be the executable progam, MYPROG.EXE. The link process can, of course, be more complicated for the user with additional Pascal modules or librarys, but he hardly needs instructions. Other users, with access to an appropriate LIB.EXE or LIB.COM program, may choose to create PASCLIB.LIB or include PASCLIB.OBJ into PASCAL.LIB (as I have done). TECHNICAL INFORMATION The floating point format used in the PASCLIB.OBJ module is directly compatible with that used in IBM/MS Pascal short precision. It is 32 bit, sign in the high order bit followed by the characteristic (exponent) and mantissa (fraction). See the description in your IBM/MS Pascal documentation around the description of MPSRQQ. For you Assembler Language programmers (you probably don't need much instruction), I will remind you of several considerations. To use the functions/procedures in PASCLIB.OBJ, you 1. Must include an EXTERN Compiler directive in the segment calling PASCLIB.OBJ routines, or if external to the seqment the function/ procedure namse called must be declared in an ASSIGN statement. The following names were declared as PUBLIC within PASCLIB: RANDOMIZE, RANDOM, F_ADD, F_SUB, F_MULT, F_DIV, SINLOOK, COSLOOK, IFLOAT, FLTRUNC, FROUND, FLTMOD, RSIN, RCOS, CRADDEG If you are calling F_MULT and RSIN in your program, you shold include the following statement within the segment performing the calls: EXTERN F_MULT:FAR, RSIN:FAR 2. Must use a FAR CALL to interface to the modules, thus CALL FAR PTR F_MULT or CALL FAR PTR RSIN 3. Must be familiar with the CALLing linkage for interfacing Pascal programs to Assembler language subroutines. A reminder: Parameters are passed and returned in several different ways using IBM/MS Pascal. In the case of "call by name" (where a VAR was included in the definition), the ADDRESS of the variable is pushed on the stack prior to the call. In the case of "call by value" (No VAR in the definition), the actual parameter, itself, is pushed on the stack. For floating point (real) values, the low-order word is pushed first followed by the high order byte (for call by value). For call by name, the address of the low-order byte is pushed on the stack. For procedures (SINLOOK and COSLOOK), the result is returned in the return variable (in this case, the second variable). For functions, the result is returned in the last address pushed on the stack prior to the CALL, and the address of the answer is returned in the AX register. Remember that values/addresses must be pushed on the stack in the sequence that they appear in the Pascal definitions, from left to right, prior to the CALL. I hope you benefit from using PASCLIB, and I will appreciate any feedback (good or bad) about PASCLIB. I will attempt to fix any bugs that crop up, but can only gurantee a "best effort". I have found that it's accuracy is essentially the same as that of the BASICA Interpreter and its speed is "Out of Sight". Have fun!